home *** CD-ROM | disk | FTP | other *** search
/ EnigmA Amiga Run 1996 June / EnigmA AMIGA RUN 08 (1996)(G.R. Edizioni)(IT)[!][issue 1996-06][EARSAN CD VII].iso / earcd / editor / proged20.lha / installproged / sources / DevManual_ENG next >
Text File  |  1996-03-11  |  12KB  |  454 lines
  1.  
  2.               -----------------------------------------------
  3.  
  4.                 ProgED V2.0 by Giovanni Lambiase (C) 1995-96
  5.  
  6.                              Developers notes
  7.  
  8.               -----------------------------------------------
  9.  
  10.  
  11. --------------------
  12.  1. Main structures
  13. --------------------
  14.  
  15.     If you want know something about structures see file PED.h.
  16.  
  17.  
  18.  
  19. ------------
  20.  2. Scanner
  21. ------------
  22.  
  23.     A scanner must be written using an ASM function or a C function.
  24. If you use a C function you MUST use __asm, __saveds & register __XX
  25. directives of SAC/C. Hovewer you MUST NOT use startup modules. The first
  26. location must be the start location of your function. The search function
  27. will receive two arguments in A0 & A1 registers:
  28.  
  29.     A0: Address of the line buffer. It points to a string 0-terminated.
  30.  
  31.     A1: Address of the name buffer.
  32.  
  33.     The function MUST return in D0 register the length of the string
  34. written in the buffer pointed by A1. If your function fails in the
  35. search you must return 0.
  36.  
  37.     NOTE: You MUST, hovewer, save all register in the stack at the entry
  38.           of you function and load all them at the exit.
  39.  
  40.  
  41.  
  42. -----------
  43.  3. Folder
  44. -----------
  45.  
  46.     You may create a folder using same rules explained for scanners:
  47.  
  48.       1) Use a C Function or ASM function
  49.       2) Use __asm,__saveds & register __XX directives
  50.       3) Don't use startup modules
  51.       4) First location must be the function start
  52.       5) You must, hovewer, save all register in the stack at the entry
  53.          of you function and load all them at the exit.
  54.  
  55.     A folder will receive arguments in the following registers:
  56.  
  57.     A0: Address of PEDWindow structure. You have to work on the text
  58.         contained in this window.
  59.  
  60.     D0: Cursor column number (0=first column).
  61.  
  62.     D1: Cursor line number (0=first line). This value is ABSOLUTE. This
  63.         means that it's the REAL line number from text start (generally
  64.         line number are computed jumping over a fold!).
  65.  
  66.     A1: Address of a long-word. Using this address the function MUST
  67.         write in the long-word the start line number of the fold, if
  68.         found. To compute this value the function MUST get the
  69.         ABSOLUTE line number (0=first line).
  70.  
  71.     A2: Address of a long-word. Using this address the function MUST
  72.         write in the long-word the end line number of the fold, if
  73.         found. To Compute this value the function MUST get the
  74.         ABSOLUTE line number (0=first line).
  75.  
  76.     A3: Points to a buffer. If your function has found a fold it
  77.         must write in this buffer the name of the fold. ProgED
  78.         will show it. Generally you'll write here the name of
  79.         the function found.
  80.  
  81.     The scanner function MUST return in D0 register 1 if it found a fold,
  82. else 0. If a fold was found your function must return, also, the start
  83. & end line numbers in the longwords pointed by A1 & A2 and the function
  84. name in the buffer pointed by A3.
  85.  
  86.     NOTE: the 'FOLD ALL' function is executed calling your function
  87. on ALL lines of the text. At each call the cursor will be at the
  88. first column (D1 will contain 0).
  89.  
  90.  
  91.  
  92. ----------------
  93.  4. API Clients
  94. ----------------
  95.  
  96.     ProgED allow you to hook-up external applications (called "clients")
  97. An API client is simply an executable (written in any language). This
  98. executable must register itself at ProgED API port. Thus ProgED can
  99. trace his clients and send them some info about what they'ld do.
  100. The messages that a client can send to ProgED (in his API port called
  101. "PED_API") have the following structure:
  102.  
  103.     struct APIMessage
  104.     {
  105.         struct Message     am_Message;
  106.         ULONG              am_MsgType,
  107.                            am_MsgArg[10],
  108.                            am_RC;
  109.     }
  110.  
  111.     am_Message:
  112.  
  113.          standard exec msg.
  114.  
  115.     am_MsgType:
  116.  
  117.          Type of msg.
  118.  
  119.     am_MsgArg[]:
  120.  
  121.          Array of arguments of the msg.
  122.  
  123.     am_RC:
  124.  
  125.          Return code.
  126.  
  127.  
  128.  
  129.  
  130.     A client can send to ProgED the followings type of msgs:
  131.  
  132.     PED_API_REGISTER:
  133.  
  134.           "Register me.".In am_MsgArg[0] you must supply a pointer to an
  135.           APIClient structure. This msg return nothing.
  136.  
  137.     PED_API_UNREGISTER:
  138.  
  139.           "Unregister me.".This msg have to be used if the client want to
  140.           go away (!?!). It needs in am_MsgArg[0] the pointer you supplied
  141.           for PED_API_REGISTER. This msg return nothing,too.
  142.  
  143.     PED_API_ADD_INTERNAL_COMMAND:
  144.  
  145.           A client can add a new internal command. To do so, you have to
  146.           create an ArexxExtCmds structure and put its address in
  147.           am_MsgArg[0]. This msg return nothing,too.
  148.  
  149.  
  150.     PED_API_REM_INTERNAL_COMMAND:
  151.  
  152.           If you want to remove a previously added internal command, you
  153.           have to use this msg. Put the address of your ArexxExtCmds
  154.           structure in am_MsgArg[0]. This msg return nothing,too.
  155.  
  156.     PED_API_GET_ACTIVE_WINDOW:
  157.  
  158.           Get the address of PEDWindow structure currently active.
  159.           You'll find this address in am_RC.
  160.  
  161.     PED_API_GET_WINDOW_LIST:
  162.  
  163.           Get the pointer to the first PEDWindow structure in the ProgED
  164.           list. You'll find this address in am_RC.
  165.  
  166.     PED_GET_SCREEN_ADDRESS:
  167.  
  168.           Get the ProgED screen address. If ProgED is actually iconified
  169.           return NULL. You'll find this address in am_RC.
  170.  
  171.     PED_GET_PREFS_ADDRESS:
  172.  
  173.           Get the address of the Prefs structure in am_RC.
  174.  
  175.     PED_GET_PUBSCRNAME:
  176.  
  177.           Get the ProgED public screen name in am_RC.
  178.  
  179.     NOTE: The ArexxExtCmds structure MUST remain valid until you have
  180.           replied to the PED_API_REM_INTERNAL_COMMAND. After this you
  181.           can free or reuse it.
  182.  
  183.  
  184.  
  185.  
  186.     ProgED can send to a client the following msgs:
  187.  
  188.     PED_API_SHOW:
  189.  
  190.           "I opened my screen. My screen address is in am_MsgArg[0].The
  191.           public screen name is in am_MsgArg[1].". Using this info you
  192.           can open your windows on the ProgED screen. You'll receive
  193.           this msg ONLY if you specified NOTIFY_ON_SHOWHIDE in the
  194.           flags field of the APIClients structure (see it).
  195.  
  196.     PED_API_HIDE:
  197.  
  198.           "I'm closing my screen!". You'll receive this msg when ProgED
  199.           is about to closing its screen. Close ALL your windows. You'll
  200.           receive this msg ONLY if you specified NOTIFY_ON_SHOWHIDE in
  201.           the flags field on the APIClients structure (see it).
  202.  
  203.     PED_API_KEY:
  204.  
  205.           "User pressed a key!". The client can get the relative IntuiMessage
  206.           structure using am_MsgArg[0]. This field will contain the address
  207.           to an IntuiMessage structure specifing a RAWKEY msg. In am_MsgArg[1],
  208.           furthermore, client can get a pointer to a struct PEDWindow which
  209.           received the RAWKEY message.
  210.           You'll receive this msg ONLY if you specified NOTIFY_ON_KEY in
  211.           the flags field on the APIClients structure (see it).
  212.  
  213.           NOTE: Hovewer, when you reply this msg, ProgED will execute
  214.                 the action due to the key. You can't modify the IntuiMessage,
  215.                 too. That is an Intuition message! (:-o
  216.  
  217.     PED_API_QUIT:
  218.  
  219.           "I'm quitting!". If your client receive this msg you MUST close
  220.           all your window AND QUIT. You MUST NOT use the API port
  221.           after receving this message! Your client shouldn't try to
  222.           remove commands & registeration! YOU MUST ONLY QUIT!
  223.  
  224.  
  225.  
  226.  
  227.     Here you can find some info about APIClient structure.
  228.  
  229.  
  230.     struct APIClient
  231.     {
  232.         struct MsgPort          *ac_ClientPort;
  233.         ULONG                    ac_Notify;
  234.         char                    *ac_name;
  235.         struct APIClient        *ac_Next;
  236.     }
  237.  
  238.     ac_ClientPort:
  239.  
  240.         Address of the client message port. You must supply here a
  241.         message port. ProgED will send its message to you using this
  242.         port.
  243.  
  244.     ac_Notify:
  245.  
  246.         If you specify NOTIFY_ON_SHOW_HIDE you will get PED_API_SHOW &
  247.         PED_API_HIDE messages. Using NOTIFY_ON_KEY flag you can get
  248.         some info about key pressed with PED_API_KEY msgs.
  249.  
  250.     ac_Name:
  251.  
  252.         Client name.
  253.  
  254.     ac_Next:
  255.  
  256.         Set up to NULL. It will be filled later using the address of
  257.         next client.
  258.  
  259.  
  260.  
  261.  
  262.     struct ArexxExtCmds
  263.     {
  264.         UBYTE                    External;
  265.         char                    *Name;
  266.         char                    *Template;
  267.         void                    *Defaults[MAXREXXARGS];
  268.         LONG ASM                (*CommFunc)( RG(a0) struct CommandData *);
  269.         struct ArexxExtCmds     *NextCmd;
  270.     }
  271.  
  272.     External:
  273.  
  274.         Set up to TRUE. It means this is an "external" command.
  275.  
  276.     Name:
  277.  
  278.         Command name. Write it using case letters.
  279.  
  280.     Template:
  281.  
  282.         ReadArgs template.
  283.  
  284.     Default[]:
  285.  
  286.         Array of default values for the arguments.
  287.  
  288.     CommFunc:
  289.  
  290.         Address of the function of the command. This function must be
  291.         written in ASM or using __asm & __saveds directives. It will
  292.         receive a structure CommandData in A0 register. This function
  293.         must return in D0 register an error code (see RC_xxx defines).
  294.  
  295.     NextCmd:
  296.  
  297.         Set up to NULL.
  298.  
  299.  
  300.  
  301.  
  302.     struct CommandData
  303.     {
  304.         char              *CommandLine;
  305.         void             **CommandArgs;
  306.         struct MyWindow   *CurrentWindow,
  307.                           *FirstWindow;
  308.         struct Prefs      *CurrentPrefs;
  309.         LONG ASM (*ExecuteInternalCommand)(RG(a0) char *);
  310.     }
  311.  
  312.     CommandLine:
  313.  
  314.         This field points to a string containing the entire command
  315.         line. Use it as you like.
  316.  
  317.     CommandArgs:
  318.  
  319.         Points to an array of void *. This array is the output of
  320.         the ReadArgs function on the CommandLine String. See ReadArgs
  321.         on how to use these pointers.
  322.  
  323.     CurrentWindow:
  324.  
  325.         Points to the PEDWindow actually active.
  326.  
  327.     FirstWindow:
  328.  
  329.         Points to the first PEDWindow.
  330.  
  331.     CurrentPrefs:
  332.  
  333.         Points to a Prefs structure containing actual preferences.
  334.  
  335.     ExecuteInternalCommand:
  336.  
  337.     It's a pointer to an assembler function. You can call this
  338.         function to execute a ProgED internal command. To do so,
  339.         Put in A0 register a pointer to a string containing the
  340.         command string you wish to execute. In D0 register you
  341.         will get a return code (RC_xxx).
  342.  
  343.         NOTE: Don't use the ProgED ARexx port to execute an
  344.         internal command! Doing that you'll hang up ProgED and
  345.         the client!
  346.  
  347.  
  348.  
  349. ----------------------
  350.  5. Utility functions
  351. ----------------------
  352.  
  353.     The following C functions are useful if you want to write your own
  354. folder or scanner. You can use it in your function cutting out them.
  355. This functions search for lines in ProgED texts.
  356.  
  357.  
  358.  
  359. /*****
  360.  *
  361.  * FUNCTION:    struct Line *SearchLine(struct Line *line,int y)
  362.  *
  363.  * AIM:        Search for the y-th line (not jumping over folds) starting
  364.  *        from the first line of the text supplied by "line".
  365.  *
  366.  * RESULT:    A pointer to the searched line.
  367.  *
  368.  ****/
  369.  
  370. struct Line *SearchLine(struct Line *line,int y)
  371. {
  372.     while(((y--)>0)&&(line))    line=NextLine(line);
  373.     return(line);
  374. }
  375.  
  376.  
  377.  
  378. /*****
  379.  *
  380.  * FUNCTION:    int SearchLine2(struct Line *line,int y)
  381.  *
  382.  * AIM:        Search for the line number (jumping over folds) of the
  383.  *        line numbered "y" (not jumping over folds).
  384.  *
  385.  * RESULT:     # of the searched line.
  386.  *
  387.  ****/
  388.  
  389. int SearchLine2(struct Line *line,int y)
  390. {
  391.     int    n=0;
  392.  
  393.     while(((y--)>0)&&(line))
  394.     {
  395.         if (!line->Folder)    n++;
  396.         else    if (line->NextLine)
  397.                 if (!line->NextLine->Folder)    n++;
  398.         line=line->NextLine;
  399.     }
  400.     if (line)    return(n);
  401.     else        return(0);
  402. }
  403.  
  404.  
  405.  
  406. /*****
  407.  *
  408.  * FUNCTION:    int SearchLine3(struct Line *first,struct Line *line)
  409.  *
  410.  * AIM:        Search for the line # (not jumping over folds) of the
  411.  *        line pointed by "line"."first" points to the first
  412.  *        line of the text.
  413.  *
  414.  * RESULT:    # of the searched line.
  415.  *
  416.  ****/
  417.  
  418. int SearchLine3(struct Line *first,struct Line *line)
  419. {
  420.     long    n=0;
  421.  
  422.     while(first)
  423.     {
  424.         if (first==line)    break;
  425.         n++;
  426.         first=first->NextLine;
  427.     }
  428.     return(n);
  429. }
  430.  
  431.  
  432.  
  433. /*****
  434.  *
  435.  * FUNCTION:    struct Line *SearchLine4(struct Line *line,int y)
  436.  *
  437.  * AIM:        Search for the address of the line numbered y-th.
  438.  *        "line" points to the first line of the text.
  439.  *        The result of this function is ABSOLUTE
  440.  *        (it doesn't jump over folds).
  441.  *
  442.  * RESULT:    A pointer to the searched line.
  443.  *
  444.  ****/
  445.  
  446. struct Line *SearchLine4(struct Line *line,int y)
  447. {
  448.     while(((y--)>0)&&(line))    line=line->NextLine;
  449.     return(line);
  450. }
  451.  
  452.  
  453.  
  454.